home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Developer CD v1.1
/
Amiga Developer CD v1.1 - May 1996 (1996)(Schatztruhe)[!].iso
/
Contributions
/
IAM
/
Networking
/
Envoy-2.0
/
doc
/
nipc.doc
< prev
next >
Wrap
Text File
|
1994-12-22
|
51KB
|
1,545 lines
TABLE OF CONTENTS
nipc.library/AbortTransaction
nipc.library/AddRoute
nipc.library/AllocNIPCBuff
nipc.library/AllocNIPCBuffEntry
nipc.library/AllocTransactionA
nipc.library/AppendNIPCBuff
nipc.library/BeginTransaction
nipc.library/CheckTransaction
nipc.library/CopyFromNIPCBuff
nipc.library/CopyNIPCBuff
nipc.library/CopyToNIPCBuff
nipc.library/CreateEntityA
nipc.library/DeleteEntity
nipc.library/DeleteRoute
nipc.library/DoTransaction
nipc.library/FindEntity
nipc.library/FreeNIPCBuff
nipc.library/FreeNIPCBuffEntry
nipc.library/FreeTransaction
nipc.library/GetEntityAttrsA
nipc.library/GetEntityName
nipc.library/GetHostName
nipc.library/GetTransaction
nipc.library/LoseEntity
nipc.library/NIPCBuffLength
nipc.library/NIPCBuffPointer
nipc.library/NIPCInquiryA
nipc.library/PingEntity
nipc.library/ReplyTransaction
nipc.library/SetEntityAttrsA
nipc.library/WaitEntity
nipc.library/WaitTransaction
nipc.library/AbortTransaction nipc.library/AbortTransaction
NAME
AbortTransaction -- Abort an attempted transaction.
SYNOPSIS
AbortTransaction(transaction)
A1
VOID AbortTransaction(struct Transaction *);
FUNCTION
Aborts a Transaction that was previously started by a call to
BeginTransaction().
INPUTS
transaction - Pointer to the Transaction to abort.
RESULT
If the transaction hadn't already been completed (or failed), it will
be immediately aborted, and placed on the local Entity.
EXAMPLE
NOTES
Because local Transactions are passed by reference, a transaction
sent to a local Entity can be in such a state (being processed)
where another process may be referencing them. To ensure that
a Transaction is either aborted or completed, an AbortTransaction()
call should be followed by a WaitTransaction(). If the transaction
given has already completed (or failed), no action will be taken.
BUGS
SEE ALSO
WaitTransaction(), DoTransaction(), BeginTransaction(),
CheckTransaction()
nipc.library/AddRoute nipc.library/AddRoute
NAME
AddRoute -- Add a route/gateway for a network
SYNOPSIS
success = AddRoute(network,gateway,hops,ttl)
d0 d0 d1 d2 d3
BOOL AddRoute(ULONG,ULONG,UWORD,WORD);
FUNCTION
Adds a route for a given network to NIPC's routing tables. Gateway
tells NIPC what gateway to use for that network, and hops is the
maximum number of hops to use to get to the network. 'ttl' is
'time to live' for the route. This parameter is currently ignored,
and -1 must be passed for ttl.
INPUTS
network - network number this route is for
gateway - the gateway machine on that knows how to talk to 'network'
hops - maximum number of hops for packets going to 'network'
ttl - time to live. Must currently be set to -1.
RESULT
success - true for success, false for failure to add the route.
EXAMPLE
NOTES
BUGS
SEE ALSO
DeleteRoute()
nipc.library/AllocNIPCBuff nipc.library/AllocNIPCBuff
NAME
AllocNIPCBuff -- Allocate and initialize a NIPCBuff structure
SYNOPSIS
nipcbuff = AllocNIPCBuff(entries)
D0 D0
struct NIPCBuff *AllocNIPCBuff(entries);
FUNCTION
This function is used to allocate an NIPCBuff structure for use with
transaction data areas. Note that this function only allocates the
NIPCBuff structure, initializes it, and possibly adds a number of
NIPCBuffEntry's to it. No data area is allocated.
INPUTS
entries - The number of NIPCBuffEntry's that should be placed in the
NIPCBuff structure.
RESULT
nipcbuff - Pointer to a newly allocated and initialized NIPCBuff
structure or NULL if the NIPCBuff or the number of
NIPCBuffEntry structures couldn't be allocated.
EXAMPLE
NOTES
You MUST use this function for allocating NIPCBuff structures, or
innocent memory will get overwritten.
BUGS
SEE ALSO
FreeNIPCBuff(), <envoy/nipc.h>
nipc.library/AllocNIPCBuffEntry nipc.library/AllocNIPCBuffEntry
NAME
AllocNIPCBuffEntry -- Allocate and initialize a NIPCBuffEntry structure
SYNOPSIS
entry = AllocNIPCBuffEntry()
D0
struct NIPCBuffEntry *AllocNIPCBuffEntry();
FUNCTION
This function is used to allocate an NIPCBuffEntry structure for use
with NIPCBuff structures. Note that this function only allocates the
NIPCBuffEntry structure, and clears it. No data area is allocated.
INPUTS
None
RESULT
entry - Pointer to a newly allocated and initialized NIPCBuffEntry
structure or NULL if the NIPCBuffEntry couldn't be allocated.
EXAMPLE
NOTES
You MUST use this function for allocating NIPCBuffEntry structures, or
innocent memory will get overwritten.
BUGS
SEE ALSO
FreeNIPCBuffEntry(), <envoy/nipc.h>
nipc.library/AllocTransactionA nipc.library/AllocTransactionA
NAME
AllocTransactionA -- Allocate a transaction structure.
SYNOPSIS
transaction = AllocTransactionA(taglist)
D0 A0
struct Transaction *AllocTransactionA(struct TagItem *);
struct Transaction *AllocTransaction(tag1, tag2, tag3, ...);
FUNCTION
This function will attempt to create a Transaction structure
for the user.
INPUTS
taglist -- A pointer to a list of tags defining options and requirements
for the structure.
TRN_AllocReqBuffer:
Attempts to allocate a request buffer for you of the
size in the ti_Data field of this TagItem.
(default: no request buffer)
TRN_AllocRespBuffer:
Attempts to allocate a response buffer for you of the
size in the ti_Data field of this TagItem.
(default: no response buffer)
TRN_ReqDataNIPCBuff:
TRN_RespDataNIPCBuff:
These Tags are used to tell nipc.library that either
trans_ResponseData or trans_RequestData are pointers
to NIPCBuff structures. "Normal" programmers won't
need to use this feature.
A NULL taglist will yield the defaults which are no
allocations and no NIPCBuff structures.
RESULT
transaction -- If conditions permit, AllocTransaction() will return
a pointer to a Transaction structure. If the library is
unable to either allocate memory or meet the requirements
set by the tags passed, the function will return a NULL.
EXAMPLE
NOTES
You are completely free to allocate your own buffer space
for either a request or a response buffer. If done, you
are also responsible for freeing them.
BUGS
SEE ALSO
nipc.library/AppendNIPCBuff nipc.library/AppendNIPCBuff
NAME
AppendNIPCBuff -- Append one NIPCBuff structure to another
SYNOPSIS
result = AppendNIPCBuff(first, second)
D0 A0 A1
struct NIPCBuff *AppendNIPCBuff(struct NIPCBuff *, struct NIPCBuff *);
FUNCTION
This function may be used to append the data in one NIPCBuff to another
NIPCBuff. Essentially, it just removes the NIPCBuffEntry's from
one NIPCBuff and adds them to the other NIPCBuff (in order).
After this function completes, the second NIPCBuff will be empty.
INPUTS
first- Pointer to the NIPCBuf structure to be appended to.
second - Pointer to the NIPCBuff structure to be appended.
RESULT
result - Pointer to the first NIPCBuff
EXAMPLE
NOTES
BUGS
SEE ALSO
<envoy/nipc.h>
nipc.library/BeginTransaction nipc.library/BeginTransaction
NAME
BeginTransaction -- Start an NIPC Transaction
SYNOPSIS
BeginTransaction(dest_entity,src_entity, transaction)
A0 A1 A2
VOID BeginTransaction(struct Entity *,struct Entity *,
struct Transaction *);
FUNCTION
Attempts to begin a transaction (described appropriately by the
transaction structure) to a given entity.
INPUTS
dest_entity - An abstract data type - a "magic cookie" - that identifies
the destination entity. (From FindEntity().)
src_entity - An abstract data type - a "magic cookie" - that identifies
the source entity. (From CreateEntity().)
transaction - a pointer to the Transaction to start.
RESULT
None.
EXAMPLE
NOTES
After this function begins, the Transaction structure passed becomes
the property of the nipc.library, and CANNOT be freed until this
Transaction returns to the source Entity. Once the Transaction
returns onto the local Entity, the programmer should check
trans_Error, to verify that it completed properly.
Because data transmission isn't an instantaneous operation,
a limit must be imposed on exactly how many transactions
can be queued up at any given time. Otherwise, it would be possible
for an application program to overflow the throughput of any given
networking protocol, occupying all available memory. If the
underlying networking protocol becomes overloaded, subsequent
calls to BeginTransaction() may block until the networking
protocol is no longer overwhelmed.
BUGS
SEE ALSO
DoTransaction(), CheckTransaction(), WaitTransaction(),
AbortTransaction(), <envoy/nipc.h>
nipc.library/CheckTransaction nipc.library/CheckTransaction
NAME
CheckTransaction -- Check whether a transaction has completed or not.
SYNOPSIS
status = CheckTransaction(transaction);
D0 A1
BOOL CheckTransaction(struct Transaction *);
FUNCTION
Provides a mechanism for determining whether a Transaction previously
queued with BeginTransaction() has completed. The function
will return TRUE if the Transaction is complete (or failed), and FALSE
if the Transaction is still in progress.
INPUTS
transaction - a pointer to a Transaction structure, which describes
the details of this specific Transaction.
RESULT
None.
EXAMPLE
NOTES
CheckTransaction() will return TRUE if the Transaction has never
been sent (unlike CheckIO(), which doesn't take this situation
into account).
BUGS
SEE ALSO
DoTransaction(), BeginTransaction(), WaitTransaction(),
AbortTransaction()
nipc.library/CopyFromNIPCBuff nipc.library/CopyFromNIPCBuff
NAME
CopyFromNIPCBuff -- Copy block of memory out of a NIPCBuff structure
SYNOPSIS
actual = CopyFromNIPCBuff(src, dest, srcoffset, length)
D0 A0 A1 D0 D1
ULONG CopyFromNIPCBuff(struct NIPCBuff *, UBYTE *, ULONG, ULONG);
FUNCTION
This function is used to copy one NIPCBuff to another. The number of
bytes actually copied will be returned. If there isn't enough space
in the destination buffer, then actual will be less than length.
INPUTS
src - Pointer to the NIPCBuf structure to be copied from.
dest - Pointer to the NIPCBuff structure to be copied to.
dstoffset - Offset into dest buffer.
length - Number of bytes to copy.
RESULT
actual - Number of bytes actually copied.
EXAMPLE
NOTES
This function does not modify any of the fields in the destination
NIPCBuff structure or its NIPCBuffEntries. It will abide by the
existing values of nbe_Offset and nbe_Length.
The upshot of this is that if you want the entire data area referenced
by a NIPCBuffEntry to be copied to, you should do the following:
...
nbe->nbe_Offset = 0;
nbe->nbe_Length = nbe->nbe_PhysicalLength;
...
BUGS
Before version 40.7, this function may not work correctly due to a
bug in NIPCBuffPointer, except when the source offset is zero.
SEE ALSO
<envoy/nipc.h>
nipc.library/CopyNIPCBuff nipc.library/CopyNIPCBuff
NAME
CopyNIPCBuff -- Copy a NIPCBuff structure
SYNOPSIS
actual = CopyNIPCBuff(src, dest, srcoffset, dstoffset, length)
D0 A0 A1 D0 D1 D2
ULONG CopyNIPCBuff(struct NIPCBuff *, struct NIPCBuff *,
ULONG, ULONG, ULONG);
FUNCTION
This function is used to copy one NIPCBuff to another. The number of
bytes actually copied will be returned. If there isn't enough space
in the destination buffer, then actual will be less than length.
INPUTS
src - Pointer to the NIPCBuf structure to be copied from.
dest - Pointer to the NIPCBuff structure to be copied to.
srcoffset - Offset into src buffer.
dstoffset - Offset into dest buffer.
length - Number of bytes to copy.
RESULT
actual - Number of bytes actually copied.
EXAMPLE
NOTES
This function does not modify any of the fields on the src or data
NIPCBuff structures or their NIPCBuffEntries. It will abide by
the current values of nbe_Offset and nbe_Length on both the source
and desitnation buffers.
The upshot of this is that if you want the entire data area referenced
by a NIPCBuffEntry to be copied from/to, you should do the following:
...
nbe->nbe_Offset = 0;
nbe->nbe_Length = nbe->nbe_PhysicalLength;
...
BUGS
Before version 40.7, this function may not work correctly due to a
bug in NIPCBuffPointer, except when both source and destination offsets
are zero.
SEE ALSO
<envoy/nipc.h>
nipc.library/CopyToNIPCBuff nipc.library/CopyToNIPCBuff
NAME
CopyToNIPCBuff -- Copy block of memory into a NIPCBuff structure
SYNOPSIS
actual = CopyToNIPCBuff(src, dest, dstoffset, length)
D0 A0 A1 D0 D1
ULONG CopyToNIPCBuff(UBYTE *, struct NIPCBuff *, ULONG, ULONG);
FUNCTION
This function is used to copy data from a block of memory into a
NIPCBuff. If there isn't enough space in the destination buffer,
then actual will be less than length.
INPUTS
src - Pointer to the block of memory to be copied from.
dest - Pointer to the NIPCBuff structure to be copied to.
dstoffset - Offset into destination buffer.
length - Number of bytes to copy.
RESULT
actual - Number of bytes actually copied.
EXAMPLE
NOTES
This function does not modify any of the fields in the destination
NIPCBuff structure or its NIPCBuffEntries. It will abide by the
existing values of nbe_Offset and nbe_Length.
The upshot of this is that if you want the entire data area referenced
by a NIPCBuffEntry to be copied to, you should do the following:
...
nbe->nbe_Offset = 0;
nbe->nbe_Length = nbe->nbe_PhysicalLength;
...
BUGS
Before version 40.7, this function may not work correctly due to a
bug in NIPCBuffPointer, except when the destination offset is zero.
SEE ALSO
<envoy/nipc.h>
nipc.library/CreateEntityA nipc.library/CreateEntityA
NAME
CreateEntityA -- Creates an Entity for communication.
SYNOPSIS
myentity = CreateEntityA(taglist)
D0 A0
struct Entity *CreateEntityA(struct TagItem *);
struct Entity *CreateEntity(tag1, tag2, tag3, ...);
FUNCTION
This function allows you to create an Entity for one endpoint
for communication. Given the appropriate tags, you may declare that
this entity is public - and therefore can be located by FindEntity().
INPUTS
taglist -- a list of tags that declare items such as the Entity name
(which is only necessary for public Entities), signal
bits, etc.
The following tags are defined:
ENT_Name:
Allows the user to declare the name for this entity. This
name must be unique -- and if an Entity of similar name
already exists, CreateEntity() will return NULL.
(default: no provided name)
ENT_Public:
If included, this entity is _public_, and can be found
by FindEntity() call. To declare an entity public,
you must also declare the entity name.
(default: private)
ENT_Signal:
Defines that when something arrives at this entity,
the given signal bit (bit number, not mask) should
be set. (Useful when you intend to maintain a LOT
of entities - more than possible to allocate a single
signal bit for each. In this method, a large number
of entities share the signal bit. The downside is that
every entity with that bit must be checked when
the bit is found set.)
(default: FALSE)
ENT_AllocSignal:
Asks that CreateEntity() allocate a signal bit from
the current context, and set it whenever the
entity receives any data, to set that bit. The
ti_Data field of this TagItem must be a pointer
to a ULONG which CreateEntity will fill in with the
bit number, such that you know what bit number to
Wait() on. If you provide a NULL as the ti_Data
entry, you will not be informed of the signal bit
number.
(default: signal not allocated)
A NULL taglist will provide the defaults.
RESULT
entity -- a 'magic cookie' that defines your entity, or NULL for
failure
EXAMPLE
NOTES
ENT_Signal and ENT_AllocSignal are mutually exclusive.
ENT_Public requires that you also provide ENT_Name; the
converse, however, is not true.
BUGS
SEE ALSO
DeleteEntity()
nipc.library/DeleteEntity nipc.library/DeleteEntity
NAME
DeleteEntity -- Delete an Entity
SYNOPSIS
DeleteEntity(entity);
A0
VOID DeleteEntity(struct Entity *);
FUNCTION
DeleteEntity() is the converse of CreateEntity(). It removes the
entity from NIPC lists that it may have been attached to,
frees up any resources attached to this Entity that were
allocated by CreateEntity(), and frees up the actual Entity
structure. If NULL is passed as the argument, no action will
be taken.
INPUTS
entity -- a 'magic cookie' that defines your Entity
RESULT
None.
EXAMPLE
NOTES
If an attempt is made to DeleteEntity() an Entity that has been
found (via FindEntity()), but not lost (via LoseEntity()),
the Entity being deleted will be maintained by NIPC until
all references to it no longer exist.
(The same behavior should arguably occur for an Entity on which
previously sent Transactions are yet to return.)
IMPORTANT WARNING:
Use DeleteEntity() ONLY on Entities created with CreateEntity().
Do NOT use DeleteEntity() on Entities created with FindEntity()!!
BUGS
SEE ALSO
CreateEntityA(), LoseEntity()
nipc.library/DeleteRoute nipc.library/DeleteRoute
NAME
DeleteRoute -- Remove a route/gateway for a network
SYNOPSIS
DeleteRoute(network)
d0
VOID DeleteRoute(ULONG);
FUNCTION
Removes a route for a given network from NIPC's routing tables.
INPUTS
network - network number to remove the route for
RESULT
EXAMPLE
NOTES
BUGS
SEE ALSO
AddRoute()
nipc.library/DoTransaction nipc.library/DoTransaction
NAME
DoTransaction -- Begin a Transaction, and wait for it to complete.
SYNOPSIS
DoTransaction(dest_entity,src_entity,transaction)
A0 A1 A2
VOID DoTransaction(struct Entity *, struct Entity *,
struct Transaction *);
FUNCTION
Processes an entire Transaction; it sends the request to the host
Entity and awaits the response, or returns at any point because
of an error.
INPUTS
dest_entity - An abstract data type - a "magic cookie" - that identifies
the destination entity. (From FindEntity().)
src_entity - An abstract data type - a "magic cookie" - that identifies
the destination entity. (From CreateEntity().)
transaction - a pointer to the Transaction to complete.
RESULT
None.
EXAMPLE
NOTES
DoTransaction() causes the current context to go into
a Wait() state until the Transaction is complete (or cannot be
completed. After a DoTransaction() call, the trans_Error
field should be checked to verify that the Transaction was
properly completed.
DoTransaction(), like WaitTransaction() is potentially dangerous, and
should be used carefully. If no trans_Timeout value is included,
and a server never replies the Transaction (for an unknown reason),
DoTransaction() can conceivably wait forever.
BUGS
SEE ALSO
BeginTransaction(), <envoy/nipc.h>
nipc.library/FindEntity nipc.library/FindEntity
NAME
FindEntity -- Locate a specific entity on a certain host
SYNOPSIS
remote_entity = FindEntity(hostname,entityname,src_entity,errorptr)
D0 A0 A1 A2 A3
struct Entity *FindEntity(STRPTR, STRPTR, struct Entity *,ULONG *);
FUNCTION
Attempts to locate a certain entity on a given host.
If you pass a NULL for the entityname, FindEntity will
interpret that as "the local machine".
INPUTS
hostname -- pointer to a null-terminated string declaring the
host name of the machine on which you expect to
find an Entity named the same as 'entityname'.
entityname -- pointer to a null-terminated string declaring the
name of a public entity.
src_entity -- an Entity returned by CreateEntity() that you wish to
use as the 'near' side of a communications path.
errorptr -- a pointer to a ULONG in which FindEntity() will provide
detailed error information in the event of a FindEntity()
failure. If a NULL pointer is passed, no detailed error
information will be available.
RESULT
remote_entity --
NULL if the given Entity cannot be found.
Otherwise, the magic cookie describing the Entity that you found.
EXAMPLE
NOTES
If you do a FindEntity to a different machine and it succeeds,
you have no guarantee that the remote machine's Entity will
continue to exist. Because of this, you should check all returned
Transactions for error status - if a Transaction to a remote
Entity fails because the nipc.library can no longer find the remote
Entity, the transaction will be returned as errored.
Regardless of what happens, every SUCCESSFUL FindEntity() REQUIRES an
associated LoseEntity().
Since the FindEntity() establishes a communications link between
the source and destination Entities, it's -dependant- on the
source. Therefore, do not DeleteEntity() the source entity before
LoseEntity()'ing.
BUGS
SEE ALSO
LoseEntity()
nipc.library/FreeNIPCBuff nipc.library/FreeNIPCBuff
NAME
FreeNIPCBuff -- Free a NIPCBuff structure
SYNOPSIS
FreeNIPCBuff(buff)
A0
VOID FreeNIPCBuff(struct NIPCBuff *);
FUNCTION
This function is used to free a NIPCBuff structure and any
NIPCBuffEntry structures contained in it. Note that the data areas
refereced by the NIPCBuffEntry's will not be freed.
INPUTS
buff - Pointer to the NIPCBuf structure to be freed.
RESULT
None
EXAMPLE
NOTES
You MUST use this function for freeing NIPCBuff structures, or
memory loss will occur.
BUGS
SEE ALSO
AllocNIPCBuff(), <envoy/nipc.h>
nipc.library/FreeNIPCBuffEntry nipc.library/FreeNIPCBuffEntry
NAME
FreeNIPCBuffEntry -- Free a NIPCBuffEntry structure
SYNOPSIS
FreeNIPCBuffEntry(entry)
A0
VOID FreeNIPCBuffEntry(struct NIPCBuffEntry *);
FUNCTION
This function is used to free a NIPCBuffEntry structure. Note that
the data area referenced by the NIPCBuffEntry structure will not be
freed.
INPUTS
entry - Pointer to the NIPCBuffEntry structure to be freed.
RESULT
None
EXAMPLE
NOTES
You MUST use this function for freeing NIPCBuffEntry structures, or
memory loss will occur.
BUGS
SEE ALSO
AllocNIPCBuffEntry(), <envoy/nipc.h>
nipc.library/FreeTransaction nipc.library/FreeTransaction
NAME
FreeTransaction -- Free a previously allocated Transaction structure.
SYNOPSIS
FreeTransaction(transaction)
A1
VOID FreeTransaction(struct Transaction *);
FUNCTION
Transaction structures created by AllocTransaction() (which ought be
ALL of them), must be deallocated with FreeTransaction().
FreeTransaction() frees only the Transaction structure and any
portions of the structure that were allocated by the AllocTransaction()
function.
INPUTS
transaction - a pointer to the Transaction structure to free
if NULL, no action is taken.
RESULT
None.
EXAMPLE
NOTES
Don't try to free anything that wasn't allocated by AllocTransaction().
BUGS
SEE ALSO
AllocTransactionA()
nipc.library/GetEntityAttrsA nipc.library/GetEntityAttrsA
NAME
SetEntityAttrsA -- request the attributes of an Entity. (37.106)
SetEntityAttrs -- varargs stub for GetEntityAttrsA(). (37.106)
SYNOPSIS
numProcessed = GetEntityAttrsA(entity, tagList)
A0 A1
ULONG GetEntityAttrsA(struct Entity *, struct TagItem *);
numProcessed = GetEntityAttrs(entity, firsttag, ...)
ULONG GetEntityAttrs(struct Entity *, Tag, ...);
FUNCTION
Retrieve the attributes of a specified Entity, according to
the attributes chosen in the tag list. For each entry in the
tag list, ti_Tag indentifies the attribute, and ti_Data is a
pointer to the long variable where you wish the result to be
stored.
INPUTS
entity - An Entity, created by CreateEntityA()
tagList - pointer to an array of tags.
TAGS
ENT_NameLength - Declare the size of your ENT_Name buffer.
(MUST be in the same taglist as ENT_Name!)
ENT_Name - Find the name of an Entity; ti_Data points to an
ENT_NameLength sized buffer. Cannot be used
without ENT_NameLength.
ENT_Public - Determine whether an Entity is Public or
not. (TRUE implies PUBLIC, FALSE implies
PRIVATE.)
ENT_Signal - Determine what signal bit (if any) is attached
to the given Entity. (-1 implies "none",
other signal bit number is stored in the long
pointed to by ti_Data.)
RESULT
numProcessed - the number of attributes successfully filled in.
NOTES
Attributes not included in the above taglist are unreadable.
This function exists only in revision 37.106 and later.
SEE ALSO
SetEntityAttrsA()
nipc.library/GetEntityName nipc.library/GetEntityName
NAME
GetEntityName -- Get the ASCII name associated with an Entity.
SYNOPSIS
status = GetEntityName(entity,stringptr,available);
A0 A1 D0
BOOL GetEntityName(STRPTR, STRPTR, ULONG);
FUNCTION
Given a pointer to a string, the length of the string data area, and an
entity magic-cookie, this function will attempt to return the name
associated with the Entity.
INPUTS
entity - A magic cookie, identifying an Entity.
stringptr - A pointer to a section of memory that you'd like the name
copied into.
available - The size of the above string area.
RESULT
status - Either TRUE or FALSE. Note that even if you've
referenced an entity, over a network - it's
possible that resolving what the correct name
is COULD fail.
EXAMPLE
NOTES
If the given Entity has no name, the string "UNNAMED ENTITY" will
be returned.
BUGS
SEE ALSO
nipc.library/GetHostName nipc.library/GetHostName
NAME
GetHostName -- Get the name of a specific machine.
SYNOPSIS
status = GetHostName(entity,stringptr,available)
D0 A0 A1 D0
BOOL GetHostName(struct Entity *, STRPTR, ULONG);
FUNCTION
Given a pointer to a string, the length of the string data area, and an
Entity magic-cookie, this function will attempt to return the ASCII
name associated with the host that the Entity is on.
INPUTS
entity - A magic cookie, identifying an Entity.
(If NULL, the string returned will be either
LocalRealm:LocalHost, or simply LocalHost -- depending on
whether the local machine is in a realm-based environment
or not.)
stringptr - A pointer to a section of memory that you'd like the name
copied into.
available - The size of the above string area.
RESULT
status - Either TRUE or FALSE. Note that even if you've referenced
an Entity over a network, it's possible that resolving
the name COULD fail.
EXAMPLE
NOTES
BUGS
Prior to version 40.9, GetHostName() would actually append LocalHost
to the buffer stringptr if a NULL entity was passed. Workaround:
Put an initial null byte into the buffer before calling this function.
SEE ALSO
nipc.library/GetTransaction nipc.library/GetTransaction
NAME
GetTransaction -- receive the next Transaction waiting on an Entity
SYNOPSIS
transaction = GetTransaction(entity)
D0 A0
struct Transaction *GetTransaction(struct Entity *);
FUNCTION
GetTransaction() attempts to remove the next available Transaction
from the given Entity.
INPUTS
entity -- An entity created by CreateEntity(). (Not from
FindEntity() as you're NOT allowed to read from
someone else's Entity.)
RESULT
transaction --
NULL if no Transactions are waiting,
a pointer to a Transaction structure otherwise.
EXAMPLE
NOTES
After a successful GetTransaction(), you should check the trans_Type
field of a transaction to determine whether it's a request, or a
returned failed request/response that was previously
BeginTransaction()'d from this Entity.
A transaction returned by GetTransaction will have TYPE_SERVICING
for a request. Do not confuse this with TYPE_REQUEST!
WARNING: Note that nipc.library might change how the transaction
data was packed on the transfer. You MUST check if the request
and response data buffers are NIPC buffers or not _before_
referencing them. Check the trans_Flags field for this.
Important: While nipc.library will not break any data from the source
entity into smaller pieces, it may combine them into
larger pieces. So if you find that the data is now an NIPC
buffer, you must use NIPCBuffPointer() to find the start
of your data chunks.
Don't make any further assumptions. Just adhere to these rules and
you should be safe.
BUGS
SEE ALSO
BeginTransaction(), DoTransaction(), WaitTransaction(),
ReplyTransaction(), NIPCBuffPointer(), <envoy/nipc.h>
nipc.library/LoseEntity nipc.library/LoseEntity
NAME
LoseEntity -- Free up any resources attached from a FindEntity.
SYNOPSIS
LoseEntity(entity)
A0
VOID LoseEntity(struct Entity *);
FUNCTION
This will merely free up any resources allocated with a
successful FindEntity() call.
INPUTS
entity - An abstract data type - a "magic cookie" - that
identifies an Entity. NULL for no action.
RESULT
None.
EXAMPLE
NOTES
LoseEntity() should only be used on Entities returned by FindEntity().
BUGS
SEE ALSO
CreateEntity(), DeleteEntity()
nipc.library/NIPCBuffLength nipc.library/NIPCBuffLength
NAME
NIPCBuffLength -- Determine the amount of data stored in a NIPCBuff
SYNOPSIS
length = NIPCBuffLength(buff)
D0 A0
ULONG NIPCBuffLength(struct NIPCBuff *);
FUNCTION
This function may be used to determine the total amount of data stored
in the NIPCBuff structure. Note that this does not return the total
capacity of all of the NIPCBuffEntry's.
INPUTS
buff - Pointer to a NIPCBuf structure
RESULT
length - Number of bytes stored in buff.
EXAMPLE
NOTES
BUGS
SEE ALSO
<envoy/nipc.h>
nipc.library/NIPCBuffPointer nipc.library/NIPCBuffPointer
NAME
NIPCBuffPointer -- Get a pointer to data inside a NIPCBuff
SYNOPSIS
data = NIPCBuffPointer(buff, buffentry, offset)
D0 A0 A1 D0
UBYTE *NIPCBuffPointer(struct NIPCBuff *, struct NIPCBuffEntry **,
ULONG);
FUNCTION
This function may be used to find a particular piece of data within a
NIPCBuff structure. Returns a pointer to the data item, and a pointer
to the NIPCBuffEntry that contains that item.
INPUTS
buff - Pointer to a NIPCBuf structure
offset - Offset into the NIPCBuff
buffentry - Pointer to a struct NIPCBuffEntry * to be modified
RESULT
data - Points to the byte at offset bytes into buff.
buffentry - Points to the NIPCBuffEntry that contains "data".
EXAMPLE
NOTES
BUGS
Versions of nipc.library prior to 40.7 had a problem with offsets
that exactly matched the length of a BuffEntry, and returned a pointer
past the end of the BuffEntry previous to the one it should have.
Earlier autodocs had the offset and buffentry arguments reversed. This
autodoc matches the published function prototype now.
SEE ALSO
<envoy/nipc.h>
nipc.library/NIPCInquiryA nipc.library/NIPCInquiryA
NAME
NIPCInquiryA -- Start a nipc network query
SYNOPSIS
success=NIPCInquiryA(hook, maxTime, maxResponses, tagList)
D0 A0 D0 D1 A1
BOOL NIPCInquiryA(struct Hook *, ULONG, ULONG, APTR);
success=NIPCInquiry(hook, maxTime, maxResponses, firsttag, ...)
BOOL NIPCInquiry(struct Hook *, ULONG, ULONG, Tag, ...);
FUNCTION
Starts an NIPC Network Inquiry. This function can be used to gather
data about a single machine, or to gather data for a number of
machines. Multiple types of inquiries may be made using this
function. Please see below for a description of the types of queries
and the types of information you may gather.
The Hook is called for each packet returned from hosts on the
network. Depending on how specific your query is, you may or may
not get more than one packet. When either maxTime seconds or
maxResponses packets have been received, your Hook will be called
with a null ParamPckt parameter. If your Hook routine decides that
it has all of the information it needs, it may return FALSE. This
will cause nipc.library to abort the NIPCInquiry() call.
When the Hook is called, the "Object" parameter will be a pointer to
the Task structure for the task or process that called the
NIPCInquiryA() function. This is useful if you want to signal the
calling task when the query is complete. The Hook "Message"
parameter will be a pointer to an array of TagItem structures that
contain the query response data from each responding host.
If the query fails for some reason, either due to illegal parameters
or to a lack of resources, NIPCInquiryA() will return FALSE. In this
case, your Hook function will never be called, so be careful.
INPUTS
hook(struct Hook *) - Pointer to a Hook structure to be called for
each response.
maxTime(ULONG) - The maximum number of seconds allowed for
the query. This is the absolute maximum
time allowed. Nipc.library does not add
anything to this value.
maxResponses(ULONG) - The maximum number of responses that you
will accept from the network.
tagList(struct TagItem *) - Pointer to an array of TagItem structures.
below.
TAGS
The Tags currently defined for NIPCInquiryA() are:
QUERY_IPADDR (ULONG) - This tag is used for querying a machine for
it's Network IP address. Note: This function
is provided purely for diagnostic purposes. Do
NOT depend on this tag being available in the
future.
MATCH_IPADDR (ULONG) - Query a host with the specified IP address
address. Please see the note above regarding
QUERY_IPADDR.
QUERY_REALMS (STRPTR) - Query a realmserver for the names of all known
Realms.
MATCH_REALM (STRPTR) - Only query hosts that are in a specific Realm.
QUERY_HOSTNAME (STRPTR) - Query a host for it's name.
MATCH_HOSTNAME (STRPTR) - Only query the host with the specified
hostname.
QUERY_SERVICES (STRPTR) - Query a host or hosts for the names of all
services on each machine.
MATCH_SERVICE (STRPTR) - Only query hosts that have a specific service
specified by the Tag.
QUERY_ENTITIES (STRPTR) - Query a host or hosts for the names of all
public entities on each machine.
MATCH_ENTITY (STRPTR) - Query only hosts that have a public entity
specified by the Tag.
QUERY_OWNER (STRPTR) - This Tag is currently ignored.
MATCH_OWNER (STRPTR) - This Tag is currently ignored.
QUERY_ATTNFLAGS (ULONG) - This Tag allows you to find out what bits
are set in ExecBase->AttnFlags.
MATCH_ATTNFLAGS (ULONG) - Query only hosts that have the specified
bits set in ExecBase->AttnFlags.
QUERY_LIBVERSION (VOID) - This Tag is currently ignored.
MATCH_LIBVERSION (VOID) - This Tag is currently ignored.
QUERY_CHIPREVBITS (ULONG) - This Tag alllows you to find out what
bits are set in GfxBase->ChipRevBits0.
Note: Only the lower 8 bits of the ULONG
are used.
MATCH_CHIPREVBITS (ULONG) - Query only hosts that have the specified
bits set in GfxBase->ChipRevBits0.
QUERY_MAXFASTMEM (ULONG) - Query a machine for it's maximum amount
of FAST memory.
MATCH_MAXFASTMEM (ULONG) - Query only hosts with at least the
specified amount of FAST memory.
QUERY_AVAILFASTMEM (ULONG) - Query a machine for the amount of free
FAST memory it has available.
MATCH_AVAILFASTMEM (ULONG) - Query only those hosts that have at
least the specified amount of FAST
memory available.
QUERY_MAXCHIPMEM (ULONG) - Query a machine for it's maximum amount
of installed CHIP memory.
MATCH_MAXCHIPMEM (ULONG) - Query only those hosts that have at least
the specified amount of CHIP ram installed.
QUERY_AVAILCHIPMEM (ULONG) - Query a machine for the amount of free
CHIP memory it has available.
MATCH_AVAILCHIPMEM (ULONG) - Query only those hosts that have at
least the specified amount of CHIP
memory available.
QUERY_KICKVERSION (ULONG) - Query a machine for the version and
revision of Kickstart it is running.
MATCH_KICKVERSION (ULONG) - Query only those hosts that are running
at least the specified version and
revision of Kickstart.
QUERY_WBVERSION (ULONG) - Query a machine for the version and
revision of Workbench it is running.
MATCH_WBVERSION (ULONG) - Query only those hosts that are running
at least the specified version and revision
of Workbench.
RESULT
success - Success/failure indication.
EXAMPLES
Query all hosts in realm "Software" for their Hostname, CPU type, Fast
memory installed and Kickstart version:
NIPCInquiry(myhook, \* The hook to call *\
2, \* 2 seconds max *\
15, \* 15 responses max *\
MATCH_REALM,"Software",
QUERY_HOSTNAME, 0,
QUERY_ATTNFLAGS, 0,
QUERY_MAXFASTMEM, 0,
QUERY_KICKVERSION, 0,
TAG_DONE);
The Hook would then get called for each host that responds. An example
TagList passed to the hook might be:
MATCH_REALM,"Software",
QUERY_HOSTNAME,"A2500 Test".
QUERY_ATTNFLAGS, AFF_68010|AFF_68020|AFF_68881,
QUERY_MAXFASTMEM, 4194304, (4 Megs)
QUERY_KICKVERSION, 2425007, (VERSION <<16 | REVISION)
TAG_DONE
---
Query a server for all services it has available
NIPCInquiry(myhook,
2,
2,
MATCH_REALM,"Marketing",
MATCH_HOSTNAME,"Market Server",
QUERY_SERVICES,0,
TAG_DONE)
A possible response might be:
MATCH_REALM,"Marketing",
MATCH_HOSTNAME,"Market Server",
QUERY_SERVICES,"EnvoyFileSystem",
QUERY_SERVICES,"EnvoyPrinterService",
QUERY_SERVICES,"ConferenceService",
TAG_DONE)
NOTES
This function is considered very low-level and is provided for network
diagnostic functions. You should probably be using the functions
supplied in envoy.library to do network queries. These will provide
"wrappers" for the most common types of queries.
nipc.library/PingEntity nipc.library/PingEntity
NAME
PingEntity -- Calculate the round-trip time between two Entities
SYNOPSIS
elapsedtime = PingEntity(entity, limit)
D0 A0 D0
ULONG PingEntity(struct Entity *, ULONG);
FUNCTION
INPUTS
entity - A magic cookie, identifying an Entity.
limit - Maximum number of microseconds to wait for a response.
RESULT
elapsedtime -
Total number of microseconds elapsed between attempting
to query the Entity, and a response returning. If -1L,
no response was received in the given timeout interval.
Local Entities will return 0 for elapsed time.
EXAMPLE
NOTES
BUGS
SEE ALSO
nipc.library/ReplyTransaction nipc.library/ReplyTransaction
NAME
ReplyTransaction -- Reply a Transaction.
SYNOPSIS
ReplyTransaction(transaction)
A1
VOID ReplyTransaction(struct Transaction *);
FUNCTION
This causes a Transaction received from another Entity to be
returned to the sender. You may return data with the
Transaction as well. (See the Transaction structure
definition for details.)
INPUTS
transaction -- Pointer to a Transaction structure that was
returned by a previous GetTransaction() call.
RESULT
None.
EXAMPLE
NOTES
BUGS
SEE ALSO
GetTransaction()
nipc.library/SetEntityAttrsA nipc.library/SetEntityAttrsA
NAME
SetEntityAttrsA -- change the attributes of an Entity. (37.106)
SetEntityAttrs -- varargs stub for SetEntityAttrsA(). (37.106)
SYNOPSIS
SetEntityAttrsA(entity, tagList)
A0 A1
VOID SetEntityAttrsA(struct Entity *, struct TagItem *);
SetEntityAttrs(entity, firsttag, ...)
VOID SetEntityAttrs(struct Entity *, Tag, ...);
FUNCTION
Change the attributes of a specified Entity, according to
the attributes chosen in the tag list. If an attribute is
not provided in the tag list, it's value remains unchanged.
INPUTS
entity - An Entity, created by CreateEntityA()
tagList - pointer to an array of tags providing optional
extra parameters, or NULL.
TAGS
ENT_Public - Set/Reset the public state of an Entity.
TRUE = PUBLIC, FALSE = PRIVATE.
ENT_Release - Refuse ownership of this Entity; deallocates
any signal bits created with ENT_AllocSignal.
(Not those passed in with ENT_Signal!)
Use in conjunction with ENT_Inherit to pass an
Entity between processes.
ENT_Inherit - Declares ownership of an Entity that has
previously been set with ENT_Release.
If a signal bit is necessary, this call should
be used with ENT_Signal or ENT_AllocSignal.
ENT_Signal - Set the signal bit of the Entity to the bit
value specified by ti_Data. If a bit was
previously allocated by ENT_AllocSignal, it
will be freed.
ENT_AllocSignal -
Allocate a signal bit for this Entity.
ti_Data points to a longword where you
wish the bit number to be stored, or NULL.
If a signal bit was previously allocated
by ENT_AllocSignal, it will be freed,
regardless of the success/failure of this
attribute modification.
ENT_TimeoutLinks -
Defines that any link entities connected
to this Entity should be automatically
removed after ti_Data seconds of inactivity.
0 seconds is defined as meaning "infinite"
timeouts, which is the default on
Entity creation.
NOTES
Attributes not included in the above taglist are unchangable.
This function exists only in revision 37.106 and later.
SEE ALSO
GetEntityAttrsA()
nipc.library/WaitEntity nipc.library/WaitEntity
NAME
WaitEntity -- Waits for a Transaction to arrive at an Entity.
SYNOPSIS
WaitEntity(localentity)
A0
VOID WaitEntity(struct Entity *);
FUNCTION
WaitEntity() simply causes the current process to Wait() until
something arrives at the entity.
INPUTS
entity - An abstract data type - a "magic cookie" - that
identifies an Entity.
RESULT
None.
EXAMPLE
NOTES
This is potentially dangerous - if nothing ever arrives at this
Entity, this function will never return. Unless warrented,
the caller should be using Wait() with a signal mask.
BUGS
SEE ALSO
GetTransaction()
nipc.library/WaitTransaction nipc.library/WaitTransaction
NAME
WaitTransaction -- Waits for a Transaction to complete.
SYNOPSIS
WaitTransaction(transaction)
A1
VOID WaitTransaction(struct Transaction *);
FUNCTION
Waits for the given transaction to complete, or return as failed.
INPUTS
transaction -- a pointer to a Transaction structure.
RESULT
None.
EXAMPLE
NOTES
- When doing networked transactions, if for any reason the remote
machine fails to send a response, (but no network problem exists)
and you did not supply a timeout value in trans_Timeout,
WaitTransaction() can Wait() forever.
- If you attempt to WaitTransaction() on a transaction that has
already been responded to, WaitTransaction() will return
immediately.
- If the given Transaction has not already completed, WaiTransaction()
will wait for it to complete, and then -remove- the Transaction
from the source Entity. (In other words, you don't need to
GetTransaction() it off of the Entity.)
BUGS
SEE ALSO
BeginTransaction(), DoTransaction(), exec.library/Wait()